<html>
<head><meta charset="utf-8"><title>async guide revamp · wg-async-foundations · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/index.html">wg-async-foundations</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html">async guide revamp</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="207203412"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207203412" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207203412">(Aug 17 2020 at 22:19)</a>:</h4>
<p>Hi all. As I've mentioned in the regular meetings, I've been working on an async guide originally purposed for Fuchsia developers, but can easily be repurposed to be general.  I've broken out the sections that are reviewable, so you can get a feel for the style, level of detail and general approach. Here it is, and comments should be enabled: <a href="https://hackmd.io/@betamos/rust-async-guide">https://hackmd.io/@betamos/rust-async-guide</a></p>



<a name="207673299"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207673299" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207673299">(Aug 21 2020 at 19:16)</a>:</h4>
<p>Update: So far the support has been great, and I've gotten some feedback from Tyler and Lee. I'm trying to get feedback from 2 async beginners, but haven't got any responses yet.</p>



<a name="207674343"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207674343" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207674343">(Aug 21 2020 at 19:27)</a>:</h4>
<p>One issue that came up is how to deal with the multitude of runtimes. We have a few options:</p>
<ol>
<li>Talk about runtimes only in abstract form. This way, we can't have any code that actually runs (without building our own executor, which is a no-go for this type of guide).</li>
<li>Use a minimal (reactor-free) runtime from futures::executor. This allows working examples, including spawning and synchronization, but no IO or timers. This is quite good because it demonstrates the fundamentals of async flow, but examples will be quite dull.</li>
<li>Use a "real" runtime with a reactor (currently, <span class="user-mention" data-user-id="325807">@Lee Bernick</span>  is looking at smol) in order to demonstrate a more fun TcpConn backed HTTP server.</li>
</ol>



<a name="207913888"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207913888" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207913888">(Aug 25 2020 at 00:41)</a>:</h4>
<p>Here's the guide <span class="user-mention" data-user-id="137147">@Didrik Nordstrom</span> mentioned: <a href="https://hackmd.io/@lbernick/SkgO7bCMw">https://hackmd.io/@lbernick/SkgO7bCMw</a><br>
Any feedback is welcome! Feel free to message me directly or comment here/on hackmd. I may also include a small combinators example if that's helpful.</p>



<a name="207914131"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207914131" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> tmandry <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207914131">(Aug 25 2020 at 00:45)</a>:</h4>
<p>Is it possible that you could do (3) and only have to change a very small amount of code to show examples of getting it to work with multiple runtimes?</p>



<a name="207917971"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/207917971" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#207917971">(Aug 25 2020 at 01:54)</a>:</h4>
<p>I like this idea, but it may be better handled by each runtime's documentation. We want to write a section on choosing an executor, so maybe that could include info about the similarities and differences between them.</p>



<a name="208512501"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/208512501" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#208512501">(Aug 31 2020 at 01:04)</a>:</h4>
<p>Made a PR to the async book with the example I wrote: <a href="https://github.com/rust-lang/async-book/pull/102">https://github.com/rust-lang/async-book/pull/102</a>. would love any feedback.</p>



<a name="211429542"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/211429542" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#211429542">(Sep 27 2020 at 19:05)</a>:</h4>
<p>Couldn't figure out how to add this to the project board, but I made another async book PR with info on the different executors/crates available: <a href="https://github.com/rust-lang/async-book/pull/104">https://github.com/rust-lang/async-book/pull/104</a></p>



<a name="211429688"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/211429688" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#211429688">(Sep 27 2020 at 19:08)</a>:</h4>
<p>Also, it looks like this section of the book is stale, as the linked bug is closed: <a href="https://rust-lang.github.io/async-book/07_workarounds/02_return_type.html">https://rust-lang.github.io/async-book/07_workarounds/02_return_type.html</a>. Happy to make a PR removing it, but want to double check that it's no longer an issue. <span class="user-mention" data-user-id="116009">@nikomatsakis</span> , do you know?</p>



<a name="211499891"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/211499891" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#211499891">(Sep 28 2020 at 14:31)</a>:</h4>
<p><span class="user-mention" data-user-id="325807">@Lee Bernick</span> I think that text can be removed</p>



<a name="211616283"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/211616283" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lee Bernick <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#211616283">(Sep 29 2020 at 12:56)</a>:</h4>
<p>thanks! done in <a href="https://github.com/rust-lang/async-book/pull/107">https://github.com/rust-lang/async-book/pull/107</a></p>



<a name="219283936"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219283936" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219283936">(Dec 09 2020 at 00:37)</a>:</h4>
<p>Question about terminology: Is there only one async Rust ecosystem consisting of multiple runtimes like async-std and tokio, OR are each of these a separate ecosystem? I'd like a term that represents the "runtime + utilities from that runtime" without having to elaborate every time.</p>



<a name="219284023"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219284023" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219284023">(Dec 09 2020 at 00:38)</a>:</h4>
<p>I'm assuming that "tokio etc == runtime" is the most familiar notion, but want to check in on what we all think.</p>



<a name="219284433"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219284433" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Florian Gilcher <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219284433">(Dec 09 2020 at 00:43)</a>:</h4>
<p>this is a really hard question to answer depending on the level of detail/correctness that you want</p>



<a name="219284529"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219284529" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Florian Gilcher <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219284529">(Dec 09 2020 at 00:44)</a>:</h4>
<p>preferably, there would be one ecosystem with agreed interfaces, practically, there isn't</p>



<a name="219285922"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219285922" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219285922">(Dec 09 2020 at 01:02)</a>:</h4>
<p>So the context is that I want to describe the compatibility story on a high level, and that you have to choose a "runtime".</p>



<a name="219285952"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219285952" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219285952">(Dec 09 2020 at 01:02)</a>:</h4>
<p>But this runtime is not only reactor + executor. There are also specific utilities that are meant for that runtime.</p>



<a name="219286070"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219286070" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219286070">(Dec 09 2020 at 01:04)</a>:</h4>
<p>It's ok to sacrifice correctness in the section I'm writing. We go more into detail in a specific ecosystem section.</p>



<a name="219286095"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219286095" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219286095">(Dec 09 2020 at 01:04)</a>:</h4>
<p>For now I just want to be consistent with terminology, following the principle of least surprise.</p>



<a name="219321893"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219321893" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Florian Gilcher <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219321893">(Dec 09 2020 at 11:02)</a>:</h4>
<p>I think "runtime" is okay then. It's a weak term anyways, in the sense where the JVM is also a "runtime" that comes with a lot of facilites.</p>



<a name="219322054"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/219322054" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Florian Gilcher <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#219322054">(Dec 09 2020 at 11:04)</a>:</h4>
<p>If it's okay for you that the the common glue is the stdlib Future/Tasks interfaces and the upcoming Stream trait, we are indeed talking about an ecosystems that at least aims to be _one_ ecosystem, just might not be fully there yet. I'm not sure how much you want to document the _now_.</p>



<a name="224097973"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/224097973" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Didrik Nordstrom <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#224097973">(Jan 26 2021 at 20:27)</a>:</h4>
<p>Hi, reviving this thread for a bit. Looking for one more reviewer with approval permission for <a href="https://github.com/rust-lang/async-book/pull/124">https://github.com/rust-lang/async-book/pull/124</a>.</p>



<a name="224107063"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/187312-wg-async-foundations/topic/async%20guide%20revamp/near/224107063" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/187312-wg-async-foundations/topic/async.20guide.20revamp.html#224107063">(Jan 26 2021 at 21:35)</a>:</h4>
<p>(cc <span class="user-mention" data-user-id="119031">@Esteban Küber</span> <span aria-label="point up" class="emoji emoji-1f446" role="img" title="point up">:point_up:</span> )</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>